---
title: 配置参考
i18nReady: true
githubURL: >-
  https://github.com/withastro/astro/blob/main/packages/astro/src/types/public/config.ts
---

import Since from '~/components/Since.astro'

下面的参考资料涵盖了 Astro 所有支持的配置选项。要了解有关配置 Astro 的更多信息，请阅读我们的 [配置 Astro 指南](/zh-cn/guides/configuring-astro/)。

```js
// astro.config.mjs
import { defineConfig } from 'astro/config'

export default defineConfig({
  // 你的配置在这里...
})
```

## 顶层选项

### site

<p>

**类型**：`string`
</p>

你最终部署的链接。Astro 会使用这个完整的链接来生成网站地图和最终构建的规范链接。强烈建议你设置这个配置项，以获得 Astro 最佳体验。

```js
{
  site: 'https://www.my-site.dev'
}
```


### base

<p>

**类型**：`string`
</p>

你要部署到的基本路径。Astro 在开发过程中会匹配这个路径名，这样你的开发环境就会尽可能地与你的构建环境匹配。

在下面的例子中，`astro dev` 会在 `/docs` 处启动你的服务器。

```js
{
  base: '/docs'
}
```

当使用这个选项时，你所有的静态资源导入和 URL 都需要添加 base 作为前缀。你可以通过 `import.meta.env.BASE_URL` 访问这个值。

`import.meta.env.BASE_URL` 的值将由你的 `trailingSlash` 配置所决定，无论你为 `base` 设置了什么值。

如果设置了 `trailingSlash: "always"`，则始终包含末尾斜杠。如果设置了 `trailingSlash: "never"`，即使 `base` 包含斜杠，`BASE_URL` 也不会包含末尾斜杠。

此外，Astro 在将 `config.base` 的配置值提供给集成之前会进行内部操作。由集成读取的 `config.base` 值也同样由你的 `trailingSlash` 配置决定。

在下面的示例中，在处理时 `import.meta.env.BASE_URL` 和 `config.base` 的值都将是 `/docs`：
```js
{
	 base: '/docs/',
	 trailingSlash: "never"
}
```

在下面的示例中，在处理时 `import.meta.env.BASE_URL` 和 `config.base` 的值都将是 `/docs/`：

```js
{
	 base: '/docs',
	 trailingSlash: "always"
}
```

### trailingSlash

<p>

**类型**：`'always' | 'never' | 'ignore'`<br />
**默认值**：`'ignore'`
</p>

为开发服务器和按需渲染页面的末尾斜杠设置路由匹配行为。从以下选项中选择：

  - `'ignore'` - 匹配 URL，而不管是否存在末尾的 `/`。对 "/about" 和 "/about/" 的请求将匹配到同样的路由。
  - `'always'` - 只匹配包含末尾斜杠的 URL（例如："/about/"）。为了方便起见，在生产环境中，对于没有末尾斜杠的按需渲染 URL 的请求，将会重定向到正确的 URL。但是，在开发环境中，将会显示警示页面来提醒你，你已配置为 `always` 选项。
  - `'never'` - 只匹配不包含末尾斜杠的 URL（例如："/about"）。为了方便起见，在生产环境中，对于包含末尾斜杠的按需渲染 URL 的请求，将会重定向到正确的 URL。但是，在开发环境中，将会显示警示页面来提醒你，你已配置为 `never` 选项。

当在生产环境中，因为 GET 请求发生重定向时，重定向将是 301（永久）重定向。而对于所有其他请求方法，则会是 308（永久，保留请求方法）重定向。

预渲染页面上的末尾斜杠是由托管平台处理的，他们可能会忽视你选择的配置。有关更多信息，请参阅托管平台的文档。此时，你不能使用 Astro [重定向](#redirects) 来处理这种情况。

```js
{
  // 示例：在开发过程中要求有末尾斜杠
  trailingSlash: 'always'
}
```

**另见**：

- build.format

### redirects

<p>

**类型：** `Record<string, RedirectConfig>`<br />
**默认值：** `{}`<br />
<Since v="2.9.0" />
</p>

指定重定向的映射关系。其中键为要匹配的路由，值为重定向的路径。

你可以重定向静态和动态路由，但只能重定向到相同类型的路由。例如，你不能有一个 `'/article': '/blog/[...slug]'` 的重定向。

```js
export default defineConfig({
  redirects: {
   '/old': '/new',
   '/blog/[...slug]': '/articles/[...slug]',
   '/about': 'https://example.com/about',
   '/news': {
     status: 302,
     destination: 'https://example.com/news'
 	},
   // '/product1/', '/product1' // 注意，这是不支持的
	}
})
```

对于未安装适配器的静态生成站点，这将生成一个使用 [`<meta http-equiv="refresh">` 标签](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/meta#http-equiv) 的客户端重定向，并且不支持状态码。

而使用 SSR 或以 `output: static` 模式使用静态适配器时，则支持状态码。

默认情况下，Astro 将以 `301` 的状态对重定向的 GET 请求进行处理，并对其他请求方法使用 `308` 的状态。

你可以使用重定向配置中的对象自定义 [重定向状态码](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status#redirection_messages)：

```js
export default defineConfig({
  redirects: {
    '/other': {
      status: 302,
      destination: '/place',
    },
  }
})


```

### output

<p>

**类型**：`'static' | 'server'`<br />
**默认值**：`'static'`
</p>

指定构建的输出目标。

- `static` - 默认预渲染你的所有页面，如果没有页面选择退出预渲染的话，将输出一个完全静态的站点。
- `server` - 默认使用服务器端渲染（SSR）渲染所有页面，始终输出一个服务器渲染的站点。

```js
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static'
})
```

**另见**：

- adapter

### adapter

<p>

**类型**：`AstroIntegration`
</p>

使用构建适配器将其部署到你最喜爱的服务器、无服务器或边缘主机。导入我们的第一方适配器（[Cloudflare](/zh-cn/guides/integrations-guide/cloudflare/), [Netlify](/zh-cn/guides/integrations-guide/netlify/), [Node.js](/zh-cn/guides/integrations-guide/node/), [Vercel](/zh-cn/guides/integrations-guide/vercel/)），或是探索 [社区适配器](https://astro.build/integrations/2/?search=&categories%5B%5D=adapters) 以在你的 Astro 项目中启用按需渲染。

有关 SSR 的更多信息，请参见我们的 [按需渲染指南](/zh-cn/guides/on-demand-rendering/) 以获得完整的 Astro 服务端渲染选项。

```js
import netlify from '@astrojs/netlify';
{
  // 示例：使用 Netlify 无服务器部署构建
  adapter: netlify(),
}
```

**另见**：

- output

### integrations

<p>
**类型：** `AstroIntegration[]`
</p>

用自定义集成来扩展 Astro 功能。你可以用集成来添加框架支持（如 Solid.js）、新功能（如站点地图）和新库支持（如 Partytown）。

请阅读我们的[集成指南](/zh-cn/guides/integrations-guide/)，以帮助开始使用 Astro 集成。

```js
import react from '@astrojs/react';
import mdx from '@astrojs/mdx';
{
  // 示例：添加 React + MDX 支持
  integrations: [react(), mdx()]
}
```

### root

<p>
**类型**：`string`<br />
**CLI**：`--root`<br />
**默认值**：`"."` (当前工作文件夹)
</p>

只有当你在项目根目录以外的目录下运行 `astro` CLI 命令时，你才应该提供该选项。通常，这个选项是通过 CLI 而不是 Astro 配置文件提供的，因为 Astro 需要知道项目根目录才能找到配置文件。

如果提供相对路径（例如：`--root: './my-project'`），Astro 会根据你当前的工作目录进行解析。

#### 示例

```js
{
  root: './my-project-directory'
}
```

```bash
$ astro build --root ./my-project-directory
```

### srcDir

<p>

**类型**：`string`<br />
**默认值**：`"./src"`
</p>

设置 Astro 将读取网站的目录。

这个值可以是绝对路径，也可以是相对路径。

```js
{
  srcDir: './www'
}
```

### publicDir

<p>

**类型**：`string`<br />
**默认值**：`"./public"`
</p>

设置静态资源目录。这个目录下的文件在开发过程中被提供给 `/`，在构建过程中被复制到构建目录。这些文件总是按原样提供或复制的，没有转换或捆绑。

这个值可以是绝对路径，也可以是相对路径。

```js
{
  publicDir: './my-custom-publicDir-directory'
}
```

### outDir

<p>

**类型**：`string`<br />
**默认值**：`"./dist"`
</p>

设置 `astro build` 将你的最终构建写入的目录。

这个值可以是绝对路径，也可以是相对路径。

```js
{
  outDir: './my-custom-build-directory'
}
```

**另见**：
- build.server

### cacheDir

<p>

**类型：** `string`<br />
**默认值：** `"./node_modules/.astro"`
</p>

设置用于缓存构建产物的目录。该目录中的文件将在后续构建中使用，以加快构建时间。

这个值可以是绝对路径，也可以是相对路径。

```js
{
  cacheDir: './my-custom-cache-directory'
}
```

### compressHTML

<p>

**类型：** `boolean`<br />
**默认值：** `true`
</p>

这是一个用于缩小 HTML 输出并减少 HTML 文件大小的选项。

默认情况下，Astro 会从 `.astro` 组件中，通过无损的方式来移除空格，当然也包括换行符。

为了满足对 HTML 的视觉化渲染，有些空格可能会因此而被保留。这个优化会在开发模式和最终构建中生效。

要禁用 HTML 压缩，请将 `compressHTML` 标志设置为 `false`。

```js
{
  compressHTML: false
}
```

### scopedStyleStrategy

<p>

**类型：** `'where' | 'class' | 'attribute'`<br />
**默认值：** `'attribute'`<br />
<Since v="2.4" />
</p>

指定 Astro 组件内部样式作用范围。可选项包括：
  - `'where'` - 使用 `:where` 选择器，不会增加特异性。
  - `'class'` - 使用基于类的选择器，会增加 +1 的特异性。
  - `'attribute'` - 使用 `data-` 属性，会增加 +1 的特异性。

使用 `'class'` 可以确保 Astro 组件内的元素选择器覆盖全局样式默认值（例如来自全局样式表）。

使用 `'where'` 可以更好地控制特异性，但需要使用更高特异性的选择器、层级和其他工具来控制应用的选择器。

使用 `'attribute'` 在你操作元素的 `class` 属性时很有用，这样你就可以避免你自己的样式逻辑和 Astro 的样式应用之间的冲突。

### security

<p>

**类型：** `Record<"checkOrigin", boolean> | undefined`<br />
**默认值：** `{checkOrigin: true}`<br />
<Since v="4.9.0" />
</p>

为 Astro 网站启用安全措施。

这些功能仅存在于使用 `server` 模式按需渲染的页面，或在 `static` 模式中选择退出预渲染的页面。

默认情况下，Astro 将自动检查在动态渲染的页面中，每个请求发送的 URL 是否与 "origin" 头匹配。你可以通过将 `checkOrigin` 设置为 `false` 来禁用此行为：

```js
// astro.config.mjs
export default defineConfig({
  output: "server",
  security: {
    checkOrigin: false
  }
})
```

#### security.checkOrigin

<p>

**类型：** `boolean`<br />
**默认值：** `true`<br />
<Since v="4.9.0" />
</p>

检查所有现代浏览器自动传递的 "origin" 头是否与每个 `Request` 发送的 URL 匹配。这用于提供跨站请求伪造（CSRF）保护。

"origin" 检查仅对按需渲染的页面执行，并且仅对具有以下 `content-type` 头的 `POST`、`PATCH`、`DELETE` 和 `PUT` 请求执行：`'application/x-www-form-urlencoded'`、`'multipart/form-data'`、`'text/plain'`。

如果 "origin" 头与请求的 `pathname` 不匹配，Astro 将返回 403 状态码，并不会渲染该页面。

### vite

<p>
**类型：** `ViteUserConfig`
</p>

传递额外的配置选项给 Vite。适用于需要使用一些 Astro 不支持的高级配置。

在 [vite.dev](https://cn.vite.dev/config/) 上查看完整的 `vite` 配置对象文档。

#### 示例

```js
{
  vite: {
    ssr: {
      // 示例；如果需要的话，可以强制破坏性包跳过 SSR 处理
      external: ['broken-npm-package'],
    }
  }
}
```

```js
{
  vite: {
    // 示例：直接在 Astro 项目中添加自定义 Vite 插件
    plugins: [myPlugin()],
  }
}
```

## 构建选项

### build.format

<p>

**类型**：`('file' | 'directory' | 'preserve')`<br />
**默认值**：`'directory'`
</p>

控制每个页面的输出文件格式。这个值可能会由适配器帮你设置：

  - `'file'`：Astro 将为每个路由生成一个 HTML 文件。（例如：`src/pages/about.astro` 和 `src/pages/about/index.astro` 都会打包成 `/about.html` 文件）
  - `'directory'`：Astro 将生成一个目录，其中包含每个页面的嵌套的 `index.html` 文件。 (例如：`src/pages/about.astro` 和 `src/pages/about/index.astro` 都会打包成 `/about/index.html` 文件)
  - `'preserve'`：Astro 将根据你的源文件夹中的文件生成 HTML 文件。 (例如：`src/pages/about.astro` 生成 `/about.html`，`src/pages/about/index.astro` 生成 `/about/index.html`)

```js
{
  build: {
    // 示例：在构建过程中生 成`page.html` 而不是 `page/index.html`。
    format: 'file'
  }
}
```

#### 对 Astro.url 的影响

设置 `build.format` 可以控制 `Astro.url` 在构建过程中被设置成什么。当它是：

- `directory` - `Astro.url.pathname` 将包括一个末尾斜杠，以模仿文件夹行为。（例如 `/foo/`）。
- `file` - `Astro.url.pathname` 将包括 `.html`。（例如 `/foo.html`）。

这意味着当你使用 `new URL('./relative', Astro.url)` 创建相对的连接时，开发和构建会得到一致的行为。

为了避免开发环境中末尾斜杠行为的不一致性，你可以根据构建格式将 [`trailingSlash` 选项](#trailingslash) 限制为 `'always'` 或 `'never'`：

-  `directory` - 设置 `trailingSlash: 'always'`
-  `file` - 设置 `trailingSlash: 'never'`

### build.client

<p>

**类型：**`string`<br />
**默认值：**`'./client'`
</p>

当构建一个有服务端渲染页面的网站时，控制你的客户端 CSS 和 JavaScript 的输出文件夹。
`outDir` 控制代码的构建位置。

这个值是相对于 `outDir` 的。

```js
{
  output: 'server',
  build: {
    client: './client'
  }
}
```

### build.server

<p>

**类型：**`string`<br />
**默认值：**`'./server'`
</p>

当构建为 SSR 时控制服务器 JavaScript 的输出目录。

这个值是相对于 `outDir` 的。

```js
{
  build: {
    server: './server'
  }
}
```

### build.assets

<p>

**类型**：`string`<br />
**默认值**：`'_astro'`<br />
<Since v="2.0.0" />
</p>

指定 Astro 生成的资源（例如打包的 JS 和 CSS）在构建输出中的目录。

```js
{
  build: {
    assets: '_custom'
  }
}
```
**另见**：
- outDir

### build.assetsPrefix

<p>

**类型：** `string | Record<string, string>`<br />
**默认值：** `undefined`<br />
<Since v="2.2.0" />
</p>

指定 Astro 生成的资源链接的前缀。如果资源与当前站点来自不同的域，则可以使用此选项。

这需要将你本地的 `./dist/_astro` 文件夹中的资源上传到远程域名下相应的 `/_astro/` 文件夹中。要重命名 `_astro` 路径，请在 `build.assets` 中指定一个新的目录。

要获取上传到同一域名下的所有资源（例如 `https://cdn.example.com/_astro/...`），请将 `assetsPrefix` 设置为根域名的字符串（不管你的 `base` 配置如何）：

```js
{
  build: {
    assetsPrefix: 'https://cdn.example.com'
  }
}
```

**新增于：** `astro@4.5.0`

你也可以传递一个对象给 `assetsPrefix`，以指定每种文件类型的不同域名。在这种情况下，`fallback`属性是必填的，并且它将作为默认值用于任何其他文件。

```js
{
  build: {
    assetsPrefix: {
      'js': 'https://js.cdn.example.com',
      'mjs': 'https://js.cdn.example.com',
      'css': 'https://css.cdn.example.com',
      'fallback': 'https://cdn.example.com'
    }
  }
}
```

### build.serverEntry

<p>

**类型**：`string`<br />
**默认值**：`'entry.mjs'`
</p>

当构建到 SSR 时，指定服务器入口的文件名。此入口通常取决于你要部署到的主机，并将由你的适配器为你设置。

注意，建议该文件以 `.mjs` 结尾，这样运行时就能检测到该文件是一个 JavaScript 模块。

```js
{
  build: {
    serverEntry: 'main.mjs'
  }
}
```

### build.redirects

<p>

**类型：** `boolean`<br />
**默认值：** `true`<br />
<Since v="2.6.0" />
</p>

指定是否在构建期间将重定向输出到 HTML 中。此选项仅适用于 `output: 'static'` 模式；在 SSR 中，重定向会被作为和其他响应一样对待。

此选项主要适用于具有用于重定向的特殊配置文件且不需要（或不希望）基于 HTML 的重定向的适配器。

```js
{
  build: {
    redirects: false
  }
}
```

### build.inlineStylesheets

<p>

**类型：** `'always' | 'auto' | 'never'`<br />
**默认值：** `auto`<br />
<Since v="2.6.0" />
</p>

控制项目样式是否以单独的 CSS 文件发送到浏览器还是内联到 `<style>` 标签中。可以从以下选项中进行选择：

-  `'always'` - 项目样式都内联到 `<style>` 标签中。
-  `'auto'` - 只有小于 `ViteConfig.build.assetsInlineLimit`（默认为 4kb）的样式表才会被内联。否则，项目样式将以外部样式表的形式发送。
-  `'never'` - 项目样式都以外部样式表的形式发送。

```js
{
	build: {
		inlineStylesheets: `never`,
	},
}
```

### build.concurrency

<p>

**类型：** `number`<br />
**默认值：** `1`<br />
<Since v="4.16.0" />
</p>

并行构建的页面数。

**在大多数情况下，你不应更改作为默认值的 `1`。**

仅当其他减少总体渲染时间的尝试（例如，批处理或缓存长时间运行的任务，如网络请求或数据访问）无法实现或没有帮助时，才使用此选项。如果该值设置得太高，可能会由于内存资源不足以及 JS 单线程的原因，导致页面渲染变慢。

```js
{
  build: {
    concurrency: 2
  }
}
```

:::caution[潜在的破坏性变更]
此功能是稳定的，且不被认定为是实验性功能。但是，此功能仅旨在解决困难的性能问题，并且在 [次要版本](/zh-cn/upgrade-astro/#语义化版本控制) 中可能会产生破坏性变更，以尽可能保持此选项的性能。如果你正在使用此功能，请检查每个次要版本的 [Astro 更新日志](https://github.com/withastro/astro/blob/refs/heads/next/packages/astro/CHANGELOG.md)。
:::

## 服务器选项

定制 Astro 开发服务器，适用于 `astro dev` 和 `astro preview`。

```js
{
  server: { port: 1234, host: true }
}
```

要根据运行的命令（`dev`、`preview`）设置不同的配置，也可以向这个配置选项传递函数。

```js
{
  // 示例：使用函数语法，根据命令进行定制
  server: ({ command }) => ({ port: command === 'dev' ? 4321 : 4000 })
}
```

### server.host

<p>

**类型：** `string | boolean`<br />
**默认值：** `false`<br />
<Since v="0.24.0" />
</p>

设置服务器应该监听哪些网络 IP 地址（即非本地主机 IP）。

- `false`- 不在网络 IP 地址上公开
- `true`- 侦听所有地址，包括 LAN 和公开地址
- `[custom-address]` - 在 `[custom-address]` 网络 IP 地址上公开（例如：`192.168.0.1`）。

### server.port

<p>

**类型：** `number`<br />
**默认值：** `4321`
</p>

设置服务器监听端口。

如果给定的端口已经在使用，Astro 会自动尝试下一个可用的端口。

```js
{
  server: { port: 8080 }
}
```

### server.allowedHosts

<p>

**类型：** `Array<string> | true`<br />
**默认值：** `[]`<br />
<Since v="5.4.0" />
</p>

一个主机名列表，Astro 允许响应这些主机名。当该值设置为 `true` 时，任何主机名都是允许的。

```js
{
  server: {
  	allowedHosts: ['staging.example.com', 'qa.example.com']
  }
}
```

### server.open

<p>

**类型：** `string | boolean`<br />
**默认值：** `false`<br />
<Since v="4.1.0" />
</p>

控制开发服务器是否应该在启动时在你的浏览器窗口中打开。

传递一个完整的 URL 字符串（例如："http://example.com" ）或一个路径（例如："/about"）来指定要打开的 URL。

```js
{
  server: { open: "/about" }
}
```

### server.headers

<p>

**类型：** `OutgoingHttpHeaders`<br />
**默认值：** `{}`<br />
<Since v="1.7.0" />
</p>

设置要在 `astro dev` 和 `astro preview` 中发送的自定义 HTTP 响应标头。

## Session 选项

<p>

<Since v="5.7.0" />
</p>

为你的 Astro 项目配置会话（session）存储。该功能用于以持久化方式存储会话数据，使其能够在不同请求之间被访问。部分适配器可能会提供默认的会话驱动，但你可以通过手动个人配置来覆盖它。

更多信息请参阅 [session 指南](/zh-cn/guides/sessions/)。

```js title="astro.config.mjs"
  {
    session: {
      // Unstorage 上驱动的名字
      driver: 'redis',
      // 所需项取决于驱动程序
      options: {
        url: process.env.REDIS_URL,
      },
      ttl: 3600, // 1 小时
    }
  }
```

### session.driver

<p>

**类型：** `string | undefined`<br />
<Since v="5.7.0" />
</p>

Unstorage 上用于会话存储的驱动。[Node](/zh-cn/guides/integrations-guide/node/#sessions)、[Cloudflare](/zh-cn/guides/integrations-guide/cloudflare/#sessions) 和 [Netlify](/zh-cn/guides/integrations-guide/netlify/#sessions) 适配器都会为你自动配置默认的驱动，但是如果你更倾向于手动配置，或者是你正在使用的适配器并未提供驱动，你仍然可以自己指定。

该值为 [Unstorage 驱动文档](https://unstorage.unjs.io/drivers) 的“驱动名称（Driver name）”。

```js title="astro.config.mjs" ins={4}
{
  adapter: vercel(),
  session: {
    driver: "redis",
  },
}
```
:::note
部分驱动可能需要安装额外的包。部分驱动可能会要求设置环境变量或凭证。更多信息请参阅 [Unstorage 文档](https://unstorage.unjs.io/drivers)。
:::

### session.options

<p>

**类型：** `Record<string, unknown> | undefined`<br />
**默认值：** `{}`<br />
<Since v="5.7.0" />
</p>

用于会话存储的驱动专用配置选项。该选项具体取决于你所使用的驱动程序。请参阅 [Unstorage 文档](https://unstorage.unjs.io/drivers) 以获取不同驱动的详细配置参数。


```js title="astro.config.mjs" ins={4-6}
{
   session: {
     driver: "redis",
     options: {
       url: process.env.REDIS_URL
     },
   }
}
```

### session.cookie

<p>

**类型：** `string | AstroCookieSetOptions | undefined`<br />
**默认值：** `{ name: "astro-session", sameSite: "lax", httpOnly: true, secure: true }`<br />
<Since v="5.7.0" />
</p>

用于配置会话 cookie 的选项。如果将该选项设置为字符串，则它会被用作 cookie 名称。或者，你也可以传入一个带有额外选项的对象。那么它将会和默认值一同合并。

```js title="astro.config.mjs" ins={3-4}
{
 session: {
   // 如果设置为字符串，则该项会被视为 cookie 名称。
   cookie: "my-session-cookie",
 }
}

```

```js title="astro.config.mjs" ins={4-8}
{
 session: {
   // 如果设置为对象，那么它将被视为 cookie 选项。
   cookie: {
     name: "my-session-cookie",
     sameSite: "lax",
     secure: true,
   }
 }
}
```

### session.ttl

<p>

**类型：** `number | undefined`<br />
**默认值：** {Infinity}<br />
<Since v="5.7.0" />
</p>

一个可选的默认选项，用于配置会话值直到过期的生存时间（以秒为单位）。

默认情况下，会话值会一直存续直到它们被删除或是会话被销毁，并且由于特定的时间已经过去，因此它们也不会自动过期。通过设置 `session.ttl` 能为你的会话值添加一个默认的过期时间。将 `ttl` 选项传递给 [`session.set()`](/zh-cn/reference/api-reference/#set) 将覆盖该单个条目的全局默认值。

```js title="astro.config.mjs" ins={3-4}
{
 session: {
   // 设置一个时长为 1 小时（3600 秒）的默认过期时间
   ttl: 3600,
 }
}
```

:::note
为会话值设置 `ttl` 不会在时间限制传入后自动从存储中将其删除。

存储中的值只会在 `ttl` 时间过期后尝试访问它们时，才会被删除。而此时，会话值将会为 undefined，而直到这时会话值才会被删除。

部分驱动程序同样支持 `ttl` 选项，该选项将在指定时间后自动删除会话。有关更多信息，请参阅你选定驱动的文档。
:::

## 开发工具栏选项

### devToolbar.enabled

<p>

**类型：** `boolean`<br />
**默认值：** `true`
</p>

是否启用 Astro 开发者工具栏。这个工具栏使你可以检查你的页面群岛、查看有用的性能和无障碍审计以及其他内容。

这个选项对整个项目生效，要只为你自己禁用工具栏，运行 `npm run astro preferences disable devToolbar`。要为你的所有项目禁用工具栏，运行 `npm run astro preferences disable devToolbar --global`。

## Prefetch 选项

<p>

**类型：** `boolean | object`
</p>

在你的网站上为链接启用预获取，以提供更快的页面视图过渡效果。（在使用 `<ClientRouter />` 路由器的页面上默认启用。设置 `prefetch: false` 可以选择退出此行为。）

此配置自动将预获取脚本添加到项目中的每个页面上，让你可以访问 `data-astro-prefetch` 属性。将此属性添加到页面上的任何 `<a />` 链接，以启用该页面的预获取。

```html
<a href="/about" data-astro-prefetch>about</a>
```

使用 [`prefetch.defaultStrategy`](#prefetchdefaultstrategy) 和 [`prefetch.prefetchAll`](#prefetchprefetchall) 选项进一步自定义默认的预获取行为。

查看 [预获取指南](/zh-cn/guides/prefetch/) 获取更多信息。

### prefetch.prefetchAll

<p>

**类型：** `boolean`
</p>

为所有链接启用预获取，包括那些没有 `data-astro-prefetch` 属性的链接。当使用 `<ClientRouter />` 路由器时，此值默认为 `true`。否则，默认值为 `false`。

```js
prefetch: {
	prefetchAll: true
}
```

当设置为 `true` 时，你可以通过在任何单独的链接上设置 `data-astro-prefetch="false"` 来单独禁用预获取。

```html
<a href="/about" data-astro-prefetch="false">About</a>
```

### prefetch.defaultStrategy

<p>

**类型：** `'tap' | 'hover' | 'viewport' | 'load'`<br />
**默认值：** `'hover'`
</p>

当链接上设置了 `data-astro-prefetch` 属性但没有值时，使用的默认预获取策略。

- `'tap'`：在你点击链接之前进行预获取。
- `'hover'`：当你悬停或聚焦在链接上时进行预获取。（默认）
- `'viewport'`：当链接进入视口时进行预获取。
- `'load'`：当页面加载后预获取当前页面的所有链接。

你可以通过在属性上设置值来覆盖此默认值，并为任何单独的链接选择不同的策略。

```html
<a href="/about" data-astro-prefetch="viewport">About</a>
```

## Image 选项

### image.endpoint

<p>

**类型：** `Object`<br />
**默认值：** `{route: '/_image', entrypoint: undefined}`<br />
<Since v="3.1.0" />
</p>

设置在开发和 SSR 中用于图像优化的端点。`entrypoint` 可以设置为 `undefined` 来使用默认端点。

```js
{
  image: {
    // 示例：使用自定义的图像端点 `/custom_endpoint`
    endpoint: {
      route: '/custom_endpoint',
      entrypoint: 'src/my_endpoint.ts',
    },
  },
}
```

### image.service

<p>

**类型：**`Object`<br />
**默认值：**`{entrypoint: 'astro/assets/services/sharp', config?: {}}`<br />
<Since v="2.1.0" />
</p>

设置用于 Astro 资源支持的图像服务。

该值应该是一个对象，其中包含图像服务应使用的入口点，并可选择地包含一个配置对象，用于传递给该服务。

服务的入口点可以是涵盖的服务之一，也可以是第三方包。

```js
{
  image: {
    // 示例：通过自定义配置启用基于 Sharp 的图像服务
    service: {
			 entrypoint: 'astro/assets/services/sharp',
			 config: {
				 limitInputPixels: false,
      },
		 },
  },
}
```

#### image.service.config.limitInputPixels

<p>

**类型：** `number | boolean`<br />
**默认值：** `true`<br />
<Since v="4.1.0" />
</p>

是否限制 Sharp 图像服务处理的图像大小。

设置为 `false` 来绕过 Sharp 图像服务的默认图像大小限制，以处理大图像。

### image.domains

<p>

**类型：** `Array<string>`<br />
**默认值：** `[]`<br />
<Since v="2.10.10" />
</p>

定义了一个允许进行远程图像优化的图像源域名列表。Astro 不会对其他远程图像进行优化。

该选项需要一个由域名字符串组成的数组，但不允许使用通配符。或者你也可以使用 [`image.remotePatterns`](#imageremotepatterns) 来定义一组允许的源 URL 模式。

```js
// astro.config.mjs
{
  image: {
    // 示例：允许来自单个域名的远程图像优化。
    domains: ['astro.build'],
  },
}
```

### image.remotePatterns

<p>

**类型：** `Array<RemotePattern>`<br />
**默认值：** `[]`<br />
<Since v="2.10.10" />
</p>

定义了允许进行远程图像优化的图像源 URL 模式列表。

`remotePatterns` 可以通过以下四个属性进行配置：

1. protocol
2. hostname
3. port
4. pathname

```js
{
  image: {
    // 示例：允许处理所有来自 aws s3 存储桶的图像
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}
```

你可以使用通配符来定义允许的 `hostname` 和 `pathname` 值，正如下所述一样。否则，只有提供的具体值将被配置：

- `hostname`:
  - 以 '**.' 开头允许所有子域名 ('endsWith')。
  - 以 '*.' 开头只允许一级子域名。

- `pathname`:
  - 以 '/**' 结尾允许所有子路由 ('startsWith')。
  - 以 '/*' 结尾只允许一级子路由。

### image.responsiveStyles

<p>

**类型：** `boolean`<br />
**默认值：** `false`<br />
<Since v="5.10.0" />
</p>

是否为响应式图片自动添加全局样式。除非你打算自己为图片设置样式，否则应该启用此选项。

此选项仅在通过配置或在图片组件上使用 `layout` 属性将 `layout` 设置为 `constrained`、`full-width` 或 `fixed` 时使用。

更多信息请参阅[图片文档](/zh-cn/guides/images/#响应式图像行为)。

### image.layout

<p>

**类型：** `ImageLayout`<br />
**默认值：** `undefined`<br />
<Since v="5.10.0" />
</p>

响应式图像的默认布局类型。可以被图像组件上的 `layout` 属性覆盖。
- `constrained` - 图像将缩放以适应容器，保持其纵横比，但不会超过指定的尺寸。
- `fixed` - 图像将保持其原始尺寸。
- `full-width` - 图像将缩放以适应容器，并保持其纵横比。

更多详情请参阅 [`layout` 组件属性](/zh-cn/reference/modules/astro-assets/#layout)。

### image.objectFit

<p>

**类型：** `ImageFit`<br />
**默认值：** `"cover"`<br />
<Since v="5.10.0" />
</p>

响应式图像的 [`object-fit` CSS 属性值](https://developer.mozilla.org/zh-CN/docs/Web/CSS/object-fit)。可以被图像组件上的 `fit` 属性覆盖。
需要设置 `layout` 的值。

更多详情请参阅 [`fit` 组件属性](/zh-cn/reference/modules/astro-assets/#fit)。

### image.objectPosition

<p>

**类型：** `string`<br />
**默认值：** `"center"`<br />
<Since v="5.10.0" />
</p>

响应式图像的默认 [`object-position` CSS 属性值](https://developer.mozilla.org/zh-CN/docs/Web/CSS/object-position)。可以被图像组件上的 `position` 属性覆盖。
需要设置 `layout` 的值。

更多详情请参阅 [`position` 组件属性](/zh-cn/reference/modules/astro-assets/#position)。

### image.breakpoints

<p>

**类型：** `Array<number>`<br />
**默认值：** `[640, 750, 828, 1080, 1280, 1668, 2048, 2560] | [640, 750, 828, 960, 1080, 1280, 1668, 1920, 2048, 2560, 3200, 3840, 4480, 5120, 6016]`<br />
<Since v="5.10.0" />
</p>

用于生成响应式图像的断点。需要设置 `layout` 的值。完整列表通常不使用，
而是根据源和输出大小进行过滤。使用的默认值取决于使用的是本地还是远程图像服务。对于远程服务，
使用更全面的列表，因为只生成所需的尺寸。对于本地服务，列表较短以减少生成的图像数量。

## Markdown 选项

### markdown.shikiConfig

<p>

**类型：** `Partial<ShikiConfig>`
</p>

Shiki 是我们的默认语法高亮器。你可以通过 `markdown.shikiConfig` 对象配置所有选项：

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
export default defineConfig({
  markdown: {
    shikiConfig: {
      // 从 Shiki 的内置主题中选择 (或者添加你自己的)
      // https://shiki.style/themes
      theme: 'dracula',
      // 或者, 提供多个主题
      // 请参阅下面的注释，了解如何使用双明/暗主题
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // 禁用默认配色
      // https://shiki.style/guide/dual-themes#without-default-color
      // (添加于 v4.12.0)
      defaultColor: false,
      // 添加自定义语言
      // 注意：Shiki 内置了无数语言，包括 .astro！
      // https://shiki.style/languages
      langs: [],
      // 为语言添加自定义别名
      // 将别名映射到 Shiki 语言 ID：https://shiki.style/languages#bundled-languages
      // https://shiki.style/guide/load-lang#custom-language-aliases
      langAlias: {
        cjs: "javascript"
      },
      // 启用自动换行以防止水平滚动
      wrap: true,
      // 添加自定义转换器：https://shiki.style/guide/transformers
      // 在这里找到常用的转换器：https://shiki.style/packages/transformers
      transformers: [],
    },
  },
});
```

请参阅 [代码语法高亮指南](/zh-cn/guides/syntax-highlighting/) 以获取更多用法和示例。

### markdown.syntaxHighlight

<p>

**类型：** `SyntaxHighlightConfig | SyntaxHighlightConfigType | false`<br />
**默认值：** `{ type: 'shiki', excludeLangs: ['math'] }`
</p>

配置 Markdown 代码块（\`\`\`）使用哪种语法高亮器（如果有的话）。这决定了 Astro 将应用于你的 Markdown 代码块的 CSS 类。

- `shiki` - 使用 [Shiki](https://shiki.style) 高亮器（默认配置 `github-dark` 主题）
- `prism` - 使用 [Prism](https://prismjs.com/) 高亮器并[提供你自己的 Prism 样式表](/zh-cn/guides/syntax-highlighting/#添加-prism-样式表)
- `false` - 不使用语法高亮。

```js
{
  markdown: {
    // 示例：在 Markdown 中使用 prism 进行语法高亮显示
    syntaxHighlight: 'prism',
  }
}
```

对于更多对语法高亮的控制，你可以指定一个配置对象，其中包含以下列出的属性：

#### markdown.syntaxHighlight.type

<p>

**类型：** `'shiki' | 'prism'`<br />
**默认值：** `'shiki'`<br />
<Since v="5.5.0" />
</p>

应用于 Markdown 代码块的默认 CSS 类。（如果无需其他语法高亮配置，可以直接将 `markdown.syntaxHighlight` 设置为 `shiki`、`prism` 或 `false`。）

#### markdown.syntaxHighlight.excludeLangs

<p>

**类型：** `Array<string>`<br />
**默认值：** `['math']`<br />
<Since v="5.5.0" />
</p>

一个包含语言的数组，用于排除在 `markdown.syntaxHighlight.type` 中指定的默认语法高亮。在使用从 Markdown 代码块生成图表的工具（如 Mermaid.js 和 D2）时，这可能会很有用。

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    syntaxHighlight: {
      type: 'shiki',
      excludeLangs: ['mermaid', 'math'],
    },
  },
});
```

### markdown.remarkPlugins

<p>

**类型**：`RemarkPlugins`
</p>

通过自定义 [Remark 插件](https://github.com/remarkjs/remark)来定制 Markdown 构建方式。你可以导入并应用插件函数（推荐），或传递一个值为插件名的字符串。

```js
import remarkToc from 'remark-toc';
{
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: "contents" }] ]
  }
}
```

### markdown.rehypePlugins

<p>

**类型**：`RehypePlugins`
</p>

通过自定义 [Rehype 插件](https://github.com/remarkjs/remark-rehype) 插件来定制对你的 Markdown 输出内容的处理方式。你可以导入并应用插件函数（推荐），或传递一个值为插件名的字符串。

```js
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis]
  }
}
```

### markdown.gfm

<p>

**类型**：`boolean`<br />
**默认值**：`true`<br />
<Since v="2.0.0" />
</p>

Astro 默认使用 [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm)。如果要禁用它，请将`gfm`标志设置为 `false`:

```js
{
  markdown: {
    gfm: false,
  }
}
```

### markdown.smartypants

<p>

**类型**：`boolean`<br />
**默认值**：`true`<br />
<Since v="2.0.0" />
</p>

Astro 默认使用 [SmartyPants formatter](https://daringfireball.net/projects/smartypants/)。如果要禁用它，请将`smartypants`标志设置为 `false`:

```js
{
  markdown: {
    smartypants: false,
  }
}
```

### markdown.remarkRehype

<p>

**类型**：`RemarkRehype`
</p>

向 [remark-rehype](https://github.com/remarkjs/remark-rehype#api) 传递选项。

```js
{
  markdown: {
    // 示例：将脚注文本翻译成另一种语言，这里是默认的英文内容
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to reference 1" },
  },
};
```

## i18n

<p>

**类型：** `object`<br />
<Since v="3.5.0" />
</p>

配置 i18n 路由，并允许你指定一些自定义选项。

查看我们的指南以获取更多关于 [Astro 的国际化](/zh-cn/guides/internationalization/) 的信息。

### i18n.locales

<p>

**类型：** `Locales`<br />
<Since v="3.5.0" />
</p>

网站支持的所有语言环境的列表。这是一个必填字段。

语言可以列为单个代码（例如 `['en', 'es', 'pt-br']`）或映射到共享代码的 `path`（例如 `{ path: "english", codes: ["en", "en-US"]}`）。这些代码将用于确定你部署的站点的 URL 结构。

不强制任何特定的语言代码格式或语法，但是你的项目文件夹中包含的内容文件必须与列表中的 `locales` 项完全匹配。在多个 `codes` 指向自定义 URL 路径前缀的情况下，将你的内容文件存储在与配置的 `path` 相同的文件夹中。

### i18n.defaultLocale

<p>

**类型：** `string`<br />
<Since v="3.5.0" />
</p>

你的网站/应用的默认语言环境，是你指定的 `locales` 之一。这是一个必填字段。

不强制任何特定的语言代码格式或语法，但是我们建议使用小写和必要的连字符（例如 "es"，"pt-br"）以获得最大的兼容性。

### i18n.fallback

<p>

**类型：** `Record<string, string>`<br />
<Since v="3.5.0" />
</p>

当导航到不存在的页面时（例如，尚未创建翻译页面）的回退策略。

使用这个对象为你支持的每种语言声明一个回退的 `locale` 路由。如果没有指定回退，那么无法访问的页面将返回 404。

##### 示例

以下示例配置你的内容回退策略，将 `/pt-br/` 中无法访问的页面重定向到它们的 `es` 版本，将 `/fr/` 中无法访问的页面重定向到它们的 `en` 版本。无法访问的 `/es/` 页面将返回 404。

```js
export default defineConfig({
	i18n: {
		defaultLocale: "en",
		locales: ["en", "fr", "pt-br", "es"],
		fallback: {
			pt: "es",
		  fr: "en"
		}
	}
})
```

### i18n.routing

<p>

**类型：** `object | "manual"`<br />
**默认值：** `object`<br />
<Since v="3.7.0" />
</p>

控制路由策略以确定你的网站 URL。请根据你的默认语言的文件夹（或 URL）路径配置来进行设置。

```js
export default defineConfig({
	i18n: {
		defaultLocale: "en",
		locales: ["en", "fr"],
		routing: {
			prefixDefaultLocale: false,
			redirectToDefaultLocale: true,
			fallbackType: "redirect",
		}
	}
})
```

自 4.6.0 起，此选项也可以设置为 `manual`。启用此路由策略后，Astro 将**禁用**其 i18n 中间件，并且无法配置其他 `routing` 选项（例如 `prefixDefaultLocale`）。你需要自行编写路由逻辑，或者手动执行 Astro 的 i18n 中间件与自定义逻辑配合使用。

```js
export default defineConfig({
	i18n: {
		defaultLocale: "en",
		locales: ["en", "fr"],
		routing: "manual"
	}
})
```

#### i18n.routing.prefixDefaultLocale

<p>

**类型：** `boolean`<br />
**默认值：** `false`<br />
<Since v="3.7.0" />
</p>

当设为 `false` 时，只有非默认语言的 URL 才会显示语言前缀。
`defaultLocale` 不会显示语言前缀，内容文件也不会存在于本地化的文件夹中。
非默认语言的 URL 会类似于 `example.com/[locale]/content/`，而默认语言的 URL 则是 `example.com/content/`。

当设为 `true` 时，所有 URL 都会显示语言前缀。
包括默认语言在内所有的 URL 都会是 `example.com/[locale]/content/`。
包括默认语言的所有语言都会使用本地化的文件夹。

```js
export default defineConfig({
	i18n: {
		defaultLocale: "en",
		locales: ["en", "fr", "pt-br", "es"],
		routing: {
			prefixDefaultLocale: true,
		}
	}
})
```

#### i18n.routing.redirectToDefaultLocale

<p>

**类型：** `boolean`<br />
**默认值：** `true`<br />
<Since v="4.2.0" />
</p>

可以用来配置由 `src/pages/index.astro` 生成的主页 URL (`/`) 是否在设置 `prefixDefaultLocale: true` 时重定向到 `/[defaultLocale]`。

设置 `redirectToDefaultLocale: false` 可以在你的网站根目录禁用这个自动重定向：
```js
// astro.config.mjs
export default defineConfig({
  i18n:{
    defaultLocale: "en",
		locales: ["en", "fr"],
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: false
    }
  }
})
```

#### i18n.routing.fallbackType

<p>

**类型：**`"redirect" | "rewrite"`<br />
**默认值：**`"redirect"`<br />
<Since v="4.15.0" />
</p>

当 [`i18n.fallback`](#i18nfallback) 配置为避免给缺失的页面路由显示 404 页面时，此选项用于控制是将用户[重定向](/zh-cn/guides/routing/#重定向)到回退页面，还是将回退页面的内容[重写](/zh-cn/guides/routing/#重写)到原始请求的 URL 上。

默认情况下，Astro 的 i18n 路由会创建页面，将你的访问者重定向到基于你的回退配置的新目的地。浏览器将刷新并在 URL 栏中显示目的地地址。

当 `i18n.routing.fallback: "rewrite"` 配置时，Astro 则会创建页面，并将回退页面的内容重写到原始请求的 URL 上。

使用以下配置，如果你有 `src/pages/en/about.astro` 这个文件，但没有 `src/pages/fr/about.astro` 时，`astro build` 命令将生成与 `dist/en/about.html` 页面相同内容的 `dist/fr/about.html` 页面。
你的网站访问者将在 `https://example.com/fr/about/` 看到页面的英文版本，而不会被重定向。

```js
//astro.config.mjs
export default defineConfig({
	 i18n: {
    defaultLocale: "en",
    locales: ["en", "fr"],
    routing: {
    	prefixDefaultLocale: false,
    	fallbackType: "rewrite",
    },
    fallback: {
    	fr: "en",
    }
  },
})
```

### i18n.domains

<p>

**类型：** `Record<string, string>`<br />
**默认值：** `{}`<br />
<Since v="4.3.0" />
</p>

配置一个或多个支持的语言环境的 URL 模式，以使用自定义域名（或子域名）。

当一个语言环境映射到一个域名时，将不会使用 `/[locale]/` 路径前缀。
但是，`src/pages/` 中的本地化文件夹仍然是必需的，包括你配置的 `defaultLocale`。

任何未配置的其他语言环境都将默认使用基于路径的本地化 URL，并遵循你的 `prefixDefaultLocale` 策略（例如 `https://example.com/[locale]/blog`）。

```js
//astro.config.mjs
export default defineConfig({
	 site: "https://example.com",
	 output: "server", // 必须，没有预渲染页面
	 adapter: node({
	   mode: 'standalone',
	 }),
	 i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    prefixDefaultLocale: false,
    domains: {
      fr: "https://fr.example.com",
      es: "https://example.es"
    }
  },
})
```

由 `astro:i18n` 辅助函数 [`getAbsoluteLocaleUrl()`](/zh-cn/reference/modules/astro-i18n/#getabsolutelocaleurl) 和 [`getAbsoluteLocaleUrlList()`](/zh-cn/reference/modules/astro-i18n/#getabsolutelocaleurllist) 返回的 URL 以及构建的页面路由，都将使用 `i18n.domains` 中设置的选项。  

请参阅 [国际化指南](/zh-cn/guides/internationalization/#domains) 了解更多详情，包括此功能的限制。

## env

<p>

**类型：** `object`<br />
**默认值：** `{}`<br />
<Since v="5.0.0" />
</p>

类型安全的环境变量的配置选项。

有关 [Astro 中环境变量](/zh-cn/guides/environment-variables/)的更多信息，请参阅我们的指南。

### env.schema

<p>

**类型：** `EnvSchema`<br />
**默认值：** `{}`<br />
<Since v="5.0.0" />
</p>

使用 `envField` 定义环境变量的数据类型和属性：`context`（client 或 server）、`access`（public 或 secret）、要使用的 `default` 值，以及此环境变量是否是 `optional`（默认为 `false`）。

```js
// astro.config.mjs
import { defineConfig, envField } from "astro/config"

export default defineConfig({
  env: {
    schema: {
      API_URL: envField.string({ context: "client", access: "public", optional: true }),
      PORT: envField.number({ context: "server", access: "public", default: 4321 }),
      API_SECRET: envField.string({ context: "server", access: "secret" }),
    }
  }
})
```

`envField` 支持四种数据类型：string、number、enum 和 boolean。`context` 和 `access` 是所有数据类型的必需属性。以下显示了每种数据类型可用的所有属性的完整列表：

```js
import { envField } from "astro/config"

envField.string({
   // context & access
   optional: true,
   default: "foo",
   max: 20,
   min: 1,
   length: 13,
   url: true,
   includes: "oo",
   startsWith: "f",
   endsWith: "o",
})
envField.number({
   // context & access
   optional: true,
   default: 15,
   gt: 2,
   min: 1,
   lt: 3,
   max: 4,
   int: true,
})
envField.boolean({
   // context & access
   optional: true,
   default: true,
})
envField.enum({
   // context & access
   values: ['foo', 'bar', 'baz'], // 必需
   optional: true,
   default: 'baz',
})
```

### env.validateSecrets

<p>

**类型：** `boolean`<br />
**默认值：** `false`<br />
<Since v="5.0.0" />
</p>

当启动 dev 服务器或运行构建时，是否在服务器上验证私密环境变量。

默认情况下，只有在启动 dev 服务器或运行构建时才会在服务器上验证公共变量，私密变量只在运行时验证。如果启用，私密变量也将在启动时检查。这在某些持续集成（CI）管道中很有用，以确保在部署之前正确设置所有的私密信息。

```js
// astro.config.mjs
import { defineConfig, envField } from "astro/config"

export default defineConfig({
  env: {
    schema: {
      // ...
    },
    validateSecrets: true
  }
})
```
